OpenEdge Development:<br />Programming Interfaces Managing client login sessions

A given Progress 4GL session can create and maintain multiple client-principal objects, and hence multiple client login sessions for different identities. These login sessions then each function according to the particular identity they represent and selected database options.

Requirements for using client login sessions

The common requirement for creating client login sessions for all types of user identities is to initialize some required data values for the session, including (among others) an authenticated user ID. You can authenticate this ID at run time using any acceptable method, including the OpenEdge internal authentication system (_User table) or any external authentication system that you can access from the Progress 4GL. For more information, see the "Authenticating user identities" section.

You set these required data values using attributes and methods of a client-principal object. You must complete the initialization of these values and seal the client-principal object in order to begin the client login session. Sealing a client-principal object prevents any further changes to its initialized data values and allows it to be used for validating and setting user identities.

If you use an external authentication system, you must also create a corresponding domain entry in the appropriate trusted domain registry to represent the 4GL code that handles the authentication:

The database trusted domain registry for each connected OpenEdge RDBMS where you set a database connection ID.

The application trusted domain registry for each 4GL session where you set a Progress session ID.

This domain entry must be available in the appropriate trusted domain registry before you use the client-principal object to validate any user ID that has been authenticated using the corresponding authentication system. For a database trusted domain registry, you can create this entry at database configuration time, before you run the application. For an application trusted domain registry, you must create the entry at application run time when you build the registry for the 4GL session. Optionally, a database can also be configured to trust the application domain registry, instead of its own database domain registry, to validate its database connection ID.

Your application might rely on multiple external authentication systems to authenticate user IDs. However, to be acceptable for asserting a user identity, a given authentication system must have a corresponding and enabled domain entry registered in the trusted domain registry that you use to assert the user identity.

Each domain entry requires an access code (sometimes referred to as a domain key). An access code is a the password-like value that you set for the Access Code field of the Authentication System Domains dialog box in Data Administration for your database’s trusted domain registry, or that you pass as a parameter to create a domain entry in your application’s trusted domain registry. For each enabled domain entry used to validate a user identity, your application needs access to the corresponding access code value in order to seal the client-principal object for validation. You can input this value at run time or otherwise hide it somewhere within your application code.

If you want the client login session recorded in an OpenEdge RDBMS, you must select the Record Authenticated Client Sessions option in the Database Options dialog box of the Data Administration tool or the character-mode Data Dictionary. With client session recording enabled, for each client login session that you successfully start, OpenEdge generates a single _client-session record keyed on the client login session ID.

The contents of this record come from selected attributes of the client-principal object handle, selected 4GL session attributes, and, if auditing is enabled, values derived from active audit policy data. For more information on the _client-session table and relevant audit policy data, see OpenEdge Getting Started: Core Business Services .

Starting and maintaining client login sessions

You can start and manage client login sessions in a similar manner for any type of identity that you create. The following steps generally apply in all cases.

Create a client-principal object using the CREATE CLIENT-PRINCIPAL statement.

Initialize all required, and any optional, attributes of the client-principal object handle and also any application-defined properties that you want to associate with the client login session using the SET-PROPERTY( ) method on the client-principal object handle. For more information on these attributes, see Table 2–3. For more information on the SET-PROPERTY( ) method, see Table 2–4.

Authenticate the user ID that you set for the client-principal object.

If the user ID that you set fails to authenticate, you can call the AUTHENTICATION-FAILED( ) method on the client-principal object handle (see Table 2–4) to freeze all settings for the client-principal object. At this point, you cannot create a client login session with the specified client-principal object, and you must skip the remaining steps for using it.

When you have initialized all the client-principal object attributes that you need for a given authenticated user ID, login the client session by calling the SEAL( ) method on the client-principal object handle (see Table 2–4), which seals the client-principal object against any further changes to its data values. It also sets the read-only SEAL-TIMESTAMP attribute (see Table 2–2), which records the effective user authentication time for the client login session.

Given that the login is successful in Step 5, you can then use the client-principal object to assert and validate a user identity for the client login session. For more information, see the:

"Managing database connection IDs" section.

"Managing Progress session IDs" section.

Note: You might login the client session after a database connection ID has already been asserted and established using the OpenEdge internal authentication system. In this case, you skip Step 6.

If you need to transport the client login session between (or even within) 4GL sessions, you can export the client-principal object in one 4GL session context using the EXPORT-PRINCIPAL( ) method and import it into another session context using the IMPORT-PRINCIPAL( ) method on a different client-principal object, validating the result, if necessary, using the VALIDATE-SEAL( ) method on the newly imported client-principal object (see Table 2–4). For more information on when you might need to do this, see the "Managing application user IDs in n-tier applications" section.

To invalidate a client login session at any time or to ensure that it terminates in an unusable state, you can call the LOGOUT( ) method on the client-principal object handle (see Table 2–4). This effectively clears and resets the user identity maintained by this client-principal object to blank, and the client-principal object becomes unusable. Progress does not automatically logout or otherwise terminate a client login session, unless you set the LOGIN-EXPIRATION-TIMESTAMP attribute on the client-principal object handle (see Table 2–3), before you seal the client-principal object in Step 5.

Note: After you no longer need a client-principal object, be sure to delete it using the DELETE OBJECT statement.

At any time during initialization and management of a client login session you can query the client-principal object attributes directly and any properties you have defined using the GET-PROPERTY( ) method (see Table 2–3). Attributes you might want to query for the state of the client login session include the read-only LOGIN-STATE and STATE-DETAIL attributes (see Table 2–2), which reflect changes in the login session and the usability of the associated client-principal object.